home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / dlbox_2 / using.doc < prev   
Encoding:
Text File  |  1995-02-27  |  12.1 KB  |  258 lines
  1. DLBOX 2.0
  2. COPYRIGHT 1995 Allegory Software & William Hatcher All Rights Reserved
  3.               
  4.               DISCLAIMER OF WARRANTY
  5.  
  6. ALLEGORY SOFTWARE AND WILLIAM HATCHER (HEREIN REFERRED TO AS THE 
  7. LICENSOR) HEREBY DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE,
  8. WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
  9. IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
  10. PURPOSE.  THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY 
  11. AND PERFORMANCE OF THE SOFTWARE.  THE LICENSOR WILL NOT BE LIABLE FOR
  12. ANY SPECIAL, INCIDENTAL, CONSEQUENTIAL, INDIRECT OR SIMILAR DAMAGES DUE
  13. TO LOSS OF DATA OR ANY OTHER REASON, EVEN IF THE LICENSOR OR AN
  14. AGENT OF THE LICENSOR HAS BEEN ADVISED OF THE POSSIBLITY OF SUCH DAMAGES.
  15. IN NO EVENT SHALL THE LICENSOR'S LIABILITY FOR ANY DAMAGES EVER EXCEED
  16. THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM
  17. OF THE CLAIM.
  18.  
  19. THIS SOFTWARE AND MANUAL ARE SOLD "AS IS" AND WITHOUT WARRANTIES AS TO
  20. PERFORMANCE OF MERCHANTABILITY OR ANY OTHER WARRANTIES WHETHER EXPRESSED
  21. OR IMPLIED.  BECAUSE OF THE VARIOUS HARDWARE AND SOFTWARE ENVIRONMENTS
  22. INTO WHICH THIS PROGRAM MAY BE PUT, NO WARRANTY OF FITNESS FOR A PARTICULAR
  23. PURPOSE IS OFFERED.  
  24.  
  25. GOOD DATA PROCESSING PROCEDURE DICTATES THAT ANY PROGRAM BE THOROUGHLY
  26. TESTED WITH NON-CRITICAL DATA BEFORE RELYING ON IT.  THE USER MUST ASSUME
  27. THE ENTIRE RISK OF USING THE PROGRAM.  ANY LIABILITY OF THE SELLER WILL BE
  28. LIMITED EXCLUSIVELY TO PRODUCT REPLACEMENT OR REFUND OF PURCHASE PRICE.
  29.  
  30. THIS AGREEMENT SHALL BE CONSTRUED AND ENFORCED IN ACCORDANCE WITH THE 
  31. LAWS OF TENNESSEE.  ANY ACTION OR PROCEEDING BROUGHT BY EITHER PARTY
  32. AGAINST THE OTHER ARISING OUT OF OR RELATED TO THIS AGREEMENT SHALL BE BROUGHT
  33. ONLY IN A FEDERAL COURT LOCATED IN TENNESSEE.  THE PARTIES HEREBY CONSENT
  34. TO JURISDICTION OF SAID COURTS.
  35.  
  36. THE USER OF DLBOX IS AUTHORIZED TO USE IT ROYALTY FREE FOR A PERIOD OF 30 
  37. CONSECUTIVE DAYS.  ANY USE BEYOND THIS REQUIRES REGISTRATION.  ALSO ANY USER 
  38. CREATING SOFTWARE USING THE DLBOX LIBRARY OR LIBRARIES THAT IS RELEASED FOR 
  39. PROFIT (COMMERCIAL OR SHAREWARE) MUST REGISTER THIS SOFTWARE.
  40.  
  41. HOW TO USE DLBOX 2.0
  42.  
  43. I.  Use of the libraries is simple.  An object class called interface_class 
  44. is the core.  Include the files inter.h and mouse.h into your program and 
  45. place the appropriate DLBOX_*.LIB file in your project list.  Presented below 
  46. is a short program illustrating the library.
  47.  
  48.     /********** Sample Code **************/
  49.     #include "submit\actual\inter.h"
  50.     #include "mouse.h"
  51.     #include <stdio.h>
  52.  
  53.     interface_class iface;
  54.  
  55.     void initg()
  56.     {
  57.       int gdriver = DETECT, gmode, errorcode;
  58.       initgraph(&gdriver, &gmode, "");
  59.       errorcode = graphresult();
  60.       settextstyle(DEFAULT_FONT,HORIZ_DIR,1);
  61.     }
  62.  
  63.     void test()
  64.     {
  65.       iface.clear();
  66.       iface.addbox(174,23,292,274);
  67.       iface.addbar("The Bar Text",1);
  68.       iface.addtitle("A Sample Title",34,41,BLUE,4,SANS_SERIF_FONT);
  69.       iface.addcheckbox("A Checkbox",32,93,2,UNCHECKED);
  70.       iface.addradio("Radio Button 1.1",32,124,3,1,UNCHECKED);
  71.       iface.addradio("Radio Button 1.2",32,138,4,1,UNCHECKED);
  72.       iface.addradio("Radio Button 1.3",32,151,5,1,UNCHECKED);
  73.       iface.addline(13,112,275,112,BLUE);
  74.       iface.addlbox(25,118,179,169,BLUE);
  75.       iface.addbutton("Button 1",27,188,8,89);
  76.       iface.addbutton("Button 2",151,188,9,110);
  77.       iface.addfield("",159,232,10,10,TEXT);
  78.       iface.addfield("",10,232,10,11,NUMBER);
  79.       iface.dodialog();
  80.  
  81.       printf("Checkbox status %d\n",iface.get_checkbox_info(2));
  82.       printf("Radio Button 1.1 status %d\n",iface.get_radio_info(3));
  83.       printf("Radio Button 1.2 status %d\n",iface.get_radio_info(4));
  84.       printf("Radio Button 1.3 status %d\n",iface.get_radio_info(5));
  85.       printf("Button 1 status %d\n",iface.get_button_info(8));
  86.       printf("Button 2 status %d\n",iface.get_button_info(9));
  87.       printf("Field 1 %s\n",iface.get_text_field_info(10));
  88.       printf("Field 2 %d\n",iface.get_text_field_info(11));
  89.     }
  90.  
  91.     main()
  92.     {
  93.       initg();
  94.       test();
  95.     }
  96.  
  97.     /********** Sample Code End**************/
  98.  
  99.  
  100. Breakdown of program:
  101. First of all the graphics mode must be initialized since the dlbox library 
  102. operates in graphics mode (VGA or EGA 16 color hi res modes).  The function 
  103. initg() does this.  The following is an analysis of the test() function.
  104.  
  105.       iface.clear();
  106. This line must appear at the beginning of any dialog box definition.  It 
  107. clears out any data left from the previously declared box and initializes 
  108. several variables.
  109.  
  110.       iface.addbox(174,23,292,274);
  111. This line must appear second in the dialog box definition.  It declares the 
  112. box position and size.  This line must appear before any of the items to be 
  113. placed in the box since they are defined relative to it.  The first two 
  114. numbers specify the x and y coordinates of the box respectively.  The second 
  115. two numbers specify the width and height respectively.
  116.  
  117.       iface.addbar("The Bar Text",BLUE);
  118. This line is optional.  If included, the dialog box will have a bar across 
  119. the top with the given string.  The text will be white and the background 
  120. color will be as specified by the second parameter.  Only 1 bar may be 
  121. declared for the box.
  122.  
  123.       iface.addtitle("A Sample Title",34,41,BLUE,4,SANS_SERIF_FONT);
  124. This line specifies a title-or text for the box.  The given string contains 
  125. the text of the title.  The following two numbers (34 and 41 in this case) 
  126. specify the x and y coordinates RELATIVE TO THE BOX for the title.  That is, 
  127. the top left of the dialog box is considered 0,0.  The next parameter 
  128. specifies the color.  The next parameter (4 in this case) is the size of the 
  129. text and the final value is the font. 
  130.  
  131.       iface.addcheckbox("A Checkbox",32,93,2,UNCHECKED);
  132. This line defines a checkbox for the dialog box.  The string is printed out 
  133. beside the box.  The first two numbers (32 and 93 in this case) specify the 
  134. relative x and y coordinates of the checkbox.  The next value (2) is very 
  135. important.  It is the item ID number and will be discussed later on.  The 
  136. last parameter signifies whether the box should be CHECKED (ON) or UNCHECKED 
  137. (OFF) by default.  
  138.  
  139.       iface.addradio("Radio Button 1.1",32,124,3,1,CHECKED);
  140.       iface.addradio("Radio Button 1.2",32,138,4,1,UNCHECKED);
  141.       iface.addradio("Radio Button 1.3",32,151,5,1,UNCHECKED);
  142. These define radio buttons.  These are similar to checkboxes.  The main 
  143. difference is that these are "grouped" in such a way that only one of a 
  144. particular group may be active (ON) at one time.  The text for the radio 
  145. button is given in the first parameter. The next two numbers specify the 
  146. coordinates for the buttons.  The next item is the item ID number (to be 
  147. discussed later).  The next parameter is unique to radio buttons and is very 
  148. important.  It signifies which GROUP a given radio button belongs to.  Only 
  149. one of a given set of radio buttons may be CHECKED at any one time (much 
  150. like radio buttons in a car).  In this case they all belong to the group 
  151. numbered 1.  The final parameter signifies if a given radio button should be 
  152. CHECKED or UNCHECKED by default.  Note that only one should be CHECKED to 
  153. maintain the logic of the radio button system.
  154.  
  155.       iface.addline(13,112,275,112,BLUE);
  156. The specifies a line.  The coordinates specify the x and y of each end of the 
  157. line.  The final parameter specifies the color.
  158.  
  159.       iface.addlbox(25,118,179,169,BLUE);
  160. Similar to the line statement, this specifies a box.  This is simply a graphic 
  161. box for purposes of boxing in segments of the dialog box.  The coordinates 
  162. specify the x and y coordinates of the top left and bottom right corner of the 
  163. box.  The final parameter specifies the color.
  164.  
  165.       iface.addbutton("Button 1",27,188,8,90);
  166.       iface.addbutton("Button 2",151,188,9,110);
  167. These statements define standard buttons for the dialog box.  The string 
  168. indicates the text to be printed on the button.  The next two values are the 
  169. x and y coordinates.  The next value is the item ID number (again to be 
  170. discussed later).  The final value is the width of the button.
  171.  
  172.       iface.addfield("",159,232,10,10,TEXT);
  173.       iface.addfield("",10,232,10,11,NUMBER);
  174. These statements define fields for the dialog box.  The first one defines a 
  175. text field and the second an integer number field.  The first parameter 
  176. specifies the default text or number (in text form) to appear in the field 
  177. when it first pops up.  The next two numbers are the x and y coordinates.  
  178. The next number is the width in characters of the field on the screen.  The 
  179. next number is the oft-mentioned but still not explained item ID number 
  180. (below, I promise).  The last parameter specifies whether the box is a TEXT 
  181. field or NUMBER field.  I recommend using the TEXT field most of the time, 
  182. even for numbers.  The NUMBER field type will return only integers, whereas 
  183. it is possible to use the TEXT field for number input.  All that is needed 
  184. is to convert the text returned into a number using one of the appropriate 
  185. Turbo C functions.
  186.  
  187.       iface.dodialog();
  188. This is a very important statement.  This statement makes the dialog box 
  189. actually happen.  It therefore must appear at the end of the dialog box 
  190. definition. 
  191.  
  192. What is the item ID number?
  193.  
  194. The item ID number is used to get return information from the dialog box.  
  195. Each item that will return data (Buttons, fields, check boxes and radio 
  196. buttons) must have a UNIQUE id number.  This is an integer number (0-32767).  
  197. The following code illustrates getting the information back from the dialog 
  198. box.  The number specified is the item ID number.
  199.  
  200.       printf("Checkbox status %d\n",iface.get_checkbox_info(2));
  201. This line gets the status of the checkbox labeled as 2.  It returns an 
  202. integer 0 to indicate that the box was not checked (or Xed in actuality) and 
  203. an integer 1 to show that the box was checked.
  204.  
  205.       printf("Radio Button 1.1 status %d\n",iface.get_radio_info(3));
  206.       printf("Radio Button 1.2 status %d\n",iface.get_radio_info(4));
  207.       printf("Radio Button 1.3 status %d\n",iface.get_radio_info(5));
  208. These lines get and print the statuses of the three radio buttons.  As with 
  209. checkboxes, the return is integer 1 if the box was checked and 0 if not.  
  210. Only one of a given radio group should be returned.  (Note that only the id 
  211. number is needed to access the data.  The radio group id is not needed.)
  212.  
  213.       printf("Button 1 status %d\n",iface.get_button_info(8));
  214.       printf("Button 2 status %d\n",iface.get_button_info(9));
  215. These lines get the statuses of the given buttons.  Integer 1 indicates the 
  216. indicated button was pressed and integer 0 means it wasn't.  
  217.  
  218.       printf("Field 1 %s\n",iface.get_text_field_info(10));
  219.       printf("Field 2 %d\n",iface.get_text_field_info(11));
  220. These lines give the return info for the fields.  The first one returns a 
  221. string since it was declared as a text field.  The second one returns an 
  222. integer since it was declared as a number field.
  223.  
  224. IMPORTANT POINTS TO KNOW
  225.  
  226. 1. The order the items are added to the interface indicates the order in 
  227. which they will appear in sequence if one uses the TAB key to go from one 
  228. to the next. 
  229.  
  230. 2. Each active item (buttons, checkboxes, fields, radio buttons) MUST have a 
  231. UNIQUE item ID number since this is how information is retrieved from the 
  232. box.
  233.  
  234. 3. All needed information must be retrieved from the box before clearing
  235. the box and setting up a new one.  A new box will zap the data from the old
  236. one.
  237.  
  238. 4. The mouse object is available through the interface_class object as mouse.
  239. With iface declared as interface_class, a typical mouse call might be:
  240.  
  241.     iface.mouse.show(); /* shows mouse */
  242.  
  243. 5. There is nothing to prevent items from being specified to be drawn outside
  244. the dialog box.  In fact, this might be useful in some situations.
  245.  
  246. 6. There MUST be at least one button (or picture button) in a dialog box.  
  247. Buttons are the only means of completing or exiting a dialog box.
  248.  
  249. 7. Picture buttons return information is accessed with get_button_info
  250. just like regular buttons.
  251.  
  252. 8. The dialog box editor program generates item id numbers.  These may be                                                                  
  253. changed as needed.  They are in the sequence that items were added to the
  254. box.
  255.  
  256. --Will Hatcher
  257.   hatcher@delphi.com
  258.